CSafeArray Class

CSafeArray is a class that provides wrapper methods for the SAFEARRAY structure, making it easy to create and manage single- and multidimensional arrays of almost any of the VARIANT-supported types. The lower bound of a CSafeArray can start at any user-defined value. Additional overloaded methods are provided for one and two-dimensional safe arrays, that are the ones most often used in COM programming.

When the class is destroyed, the array descriptor and all of the data in the array is destroyed. If objects are stored in the array, Release is called on each object in the array. Safe arrays of variant will have VariantClear called on each member and safe arrays of BSTR will have SysFreeString called on each element. IRecordInfo.RecordClear will be called to release object references and other values of a record without deallocating the record.

Include file: CSafeArray.INC.

Structures and VARTYPE

Constructors

Operators

Methods

Helper Procedures

SAFEARRAY Structure

Represents a safe array.

TYPE tagSAFEARRAY
   cDims as USHORT
   fFeatures as USHORT
   cbElements as ULONG
   cLocks as ULONG
   pvData as PVOID
   rgsabound(0 to 0) as SAFEARRAYBOUND
EBD TYPE

fFeatures Flags

Remarks

The array rgsabound is stored with the left-most dimension in rgsabound[0] and the right-most dimension in rgsabound(cDims - 1).

The fFeatures flags describe attributes of an array that can affect how the array is released. The fFeatures field describes what type of data is stored in the SAFEARRAY and how the array is allocated. This allows freeing the array without referencing its containing variant. The bits are accessed using the following constants:

Thread Safety

All public static members of the SAFEARRAY data type are thread safe. Instance members are not guaranteed to be thread safe.

For example, consider an application that uses the SafeArrayLock and SafeArrayUnlock functions. If these functions are called concurrently from different threads on the same SAFEARRAY data type instance, an inconsistent lock count may be created. This will eventually cause the SafeArrayUnlock function to return E_UNEXPECTED. You can prevent this by providing your own synchronization code.

SAFEARRAYBOUND Structure

Represents the bounds of one dimension of the array. The lower bound of the dimension is represented by lLbound, and cElements represents the number of elements in the dimension. The structure is defined as follows:

TYPE SAFEARRAYBOUND
   cElements as ULONG
   lLbound as LONG
END TYPE

Safe array Variant type

The base type of the array (the VARTYPE of each element of the array). The VARTYPE is restricted to a subset of the variant types. Neither the VT_ARRAY nor the VT_BYREF flag can be set. VT_EMPTY and VT_NULL are not valid base types for the array. All other types are legal.

Constructor (SAFEARRAYBOUND)

Creates a CSafeArray.

Multidimensional array:

CONSTRUCTOR CSafeArray (BYVAL vt AS VARTYPE, BYVAL cDims AS UINT, BYVAL prgsabounds AS SAFEARRAYBOUND PTR)
CONSTRUCTOR CSafeArray (BYREF strType AS STRING, BYVAL cDims AS UINT, BYVAL prgsabounds AS SAFEARRAYBOUND PTR)

One-dimensional array:

CONSTRUCTOR CSafeArray (BYVAL vt AS VARTYPE, BYVAL cElements AS ULONG = 0, BYVAL lLBound AS LONG = 0)
CONSTRUCTOR (BYREF strType AS STRING, BYVAL cElements AS ULONG = 0, BYVAL lLBound AS LONG = 0)

Two-dimensional array:

CONSTRUCTOR CSafeArray (BYVAL vt AS VARTYPE, BYVAL cElements1 AS ULONG, BYVAL lLBound1 AS LONG, _
   BYVAL cElements2 AS ULONG, BYVAL lLBound2 AS LONG)
CONSTRUCTOR (BYREF strType AS STRING, BYVAL cElements1 AS ULONG, BYVAL lLBound1 AS LONG, _
   BYVAL cElements2 AS ULONG, BYVAL lLBound2 AS LONG)

Usage examples

' // Two-dimensional array of BSTR
' // 2D: elements = 5, lower bound = 1
' // 2D: elements = 3, lower bound = 1
DIM rgsabounds(0 TO 1) AS SAFEARRAYBOUND = {(5, 1), (3, 1)}
DIM csa AS CSafeArray = CSafeArray(VT_BSTR, 2, @rgsabounds(0))
-or-
' // Two-dimensional array of BSTR
DIM csa AS CSafeArray = CSafeArray(VT_BSTR, 5, 1, 3, 1)

' // One-dimensional array of VT_VARIANT with 0 elements and a lower-bound of 0
DIM csa AS CSafeArray = CSafeArray(VT_VARIANT, 0, 0)
-or-
DIM csa AS CSafeArray = CSafeArray(VT_VARIANT)

' // One-dimensional array of VT_BSTR with 5 elements and a lower-bound of 1
DIM csa AS CSafeArray = CSafeArray(VT_BSTR, 5, 1)

Constructor (SAFEARRAYBOUND)

Creates a CSafeArray from another CSafeArray.

CONSTRUCTOR CSafeArray (BYREF csa AS CSafeArray)

CConstructor (SAFEARRAY PTR)

Creates a CSafeArray from a safe array.

CONSTRUCTOR CSafeArray (BYVAL psa AS SafeArray PTR)
CONSTRUCTOR CSafeArray (BYVAL psa AS SafeArray PTR, BYVAL fAttach AS BOOLEAN)

CConstructor (VARIANT PTR)

Creates a CSafeArray from a Variant of type VT_ARRAY.

CONSTRUCTOR CSafeArray (BYVAL pvar AS VARIANT PTR)

Operator * (GetPtr)

Returns a pointer to the underlying safe array descriptor.

OPERATOR * () AS ANY PTR

Remark

You can also call the GetPtr method.

Operator LET ( = )

Assigns a CSafeArray to another CSafeArray.
Assigns a safe array to a CSafeArray.
Assigns a variant of type VT_ARRAY to a CSafeArray.

OPERATOR Let (BYREF csa AS CSafeArray)
OPERATOR Let (BYVAL psa AS SAFEARRAY PTR)
OPERATOR Let (BYVAL pvar AS VARIANT PTR)

AfxStrJoin

Returns a string consisting of all of the strings in an array, each separated by a delimiter. If the delimiter is a null (zero-length) string then no separators are inserted between the string sections. If the delimiter expression is the 3-byte value of "," which may be expressed in your source code as the string literal """,""" or as Chr(34,44,34) then a leading and trailing double-quote is added to each string section. This ensures that the returned string contains standard comma-delimited quoted fields that can be easily parsed.

FUNCTION AfxStrJoin (BYREF cwsa AS CSafeArray, BYREF wszDelimiter AS WSTRING = " ") AS CWSTR

Return value

A CWSTR containing the joined string.

Usage example

DIM csa AS CSafeArray = CSafeArray("STRING", 3, 1)
csa.PutStr(1, "One")
csa.PutStr(2, "Two")
csa.PutStr(3, "Three")
DIM cws AS CWSTR = AfxStrJoin(csa, ",")
PRINT cws   ' ouput: One,Two,Three

AfxStrSplit

Splits a string into tokens, which are sequences of contiguous characters separated by any of the characters that are part of delimiters.

FUNCTION AfxStrSplit (BYREF wszStr AS CONST WSTRING, BYREF wszDelimiters AS WSTRING = " ") AS CSafeArray

Return value

A CSafeArray containing a token in each element.

Usage example

DIM cws AS CWSTR = "- This, a sample string."
DIM cwsa AS CSafeArray = AfxStrSplit(cws, " ,.-")
FOR i AS LONG = cwsa.LBound TO cwsa.UBound
  PRINT cwsa.GetStr(i)
NEXT

AfxXmlBase64Decode

Converts the contents of a Base64 mime encoded string to an ascii string.

FUNCTION AfxXmlBase64Decode (BYREF strData AS STRING) AS STRING

Return value

The decoded string on success, or a null string on failure.

Remaks

Base64 is a group of similar encoding schemes that represent binary data in an ASCII string format by translating it into a radix-64 representation. The Base64 term originates from a specific MIME content transfer encoding.

Base64 encoding schemes are commonly used when there is a need to encode binary data that needs be stored and transferred over media that are designed to deal with textual data. This is to ensure that the data remains intact without modification during transport. Base64 is used commonly in a number of applications including email via MIME, and storing complex data in XML.

AfxXmlBase64Encode

Converts the contents of a string to Base64 mime encoding.

FUNCTION AfxXmlBase64Encode (BYREF strData AS STRING) AS STRING

Return value

The encoded string on succeess, or a null string on failure.

Remaks

Base64 is a group of similar encoding schemes that represent binary data in an ASCII string format by translating it into a radix-64 representation. The Base64 term originates from a specific MIME content transfer encoding.

Base64 encoding schemes are commonly used when there is a need to encode binary data that needs be stored and transferred over media that are designed to deal with textual data. This is to ensure that the data remains intact without modification during transport. Base64 is used commonly in a number of applications including email via MIME, and storing complex data in XML.

AccessData

Retrieves a pointer to the array data and increments the lock count of an array.

FUNCTION AccessData () AS ANY PTR

Return value

IF it succeeds, it returns a pointer to the array data. If it fails, it returns a null pointer.

Append

Appends a value to the end of the one-dimensional safe array.

FUNCTION Append (BYVAL pData AS ANY PTR) AS HRESULT
FUNCTION Append (BYREF cbsData AS CBSTR) AS HRESULT
FUNCTION Append (BYREF cvData AS CVAR) AS HRESULT
FUNCTION Append (BYVAL vData AS VARIANT) AS HRESULT

Appends a string to the end of the one-dimensional safe array.

FUNCTION AppendStr (BYVAL pwszData AS WSTRING PTR) AS HRESULT

Usage examples

' // Create a one-dimensional array of doubles
'DIM csa AS CSafeArray = CSafeArray(VT_R8, 2, 1)
DIM csa AS CSafeArray = CSafeArray("DOUBLE", 2, 1)

DIM dblVal AS DOUBLE = 12345.12
csa.Put(1, @dblVal)
dblVal = 74447.34
csa.Put(2, @dblVal)
dblVal = 63535.567
csa.Append(@dblVal)

csa.Get(1, @dblVal)
print dblVal
csa.Get(2, @dblVal)
print dblVal
csa.Get(3, @dblVal)
print dblVal

' // Create a one-dimensional array of variants
'DIM csa AS CSafeArray = CSafeArray(VT_VARIANT, 2, 1)
DIM csa AS CSafeArray = CSafeArray("VARIANT", 2, 1)

csa.Put(1, CVAR("Test string"))
csa.Put(2, CVAR(12345))
csa.Append(CVAR("Test string appended"))

DIM cvOut AS CVAR
csa.Get(1, cvOut)
print cvOut
csa.Get(2, cvOut)
print cvOut
csa.Get(3, cvOut)
print cvOut

Return value

S_OK (0) on success or an HREUSLT code on failure.

Attach

Attaches a safe array to a CSafeArray object.

FUNCTION Attach (BYVAL psaSrc AS SAFEARRAY PTR) AS HRESULT

Return value

S_OK (0) on success or an HREUSLT code.

DestroyData / Clear / Erase / Reset

Destroys all the data in a safe array.

FUNCTION DestroyData () AS HRESULT

Return value

S_OK (0) on success or an HREUSLT code on failure.

Copy

Creates a copy of the safe array.

FUNCTION Copy () AS SAFEARRAY PTR

Return value

Pointer of the new array descriptor. You must free this pointer calling the API function SafeArrayDestroy.

CopyData

Copies the source array to the target array after releasing any resources in the target array. This is similar to Copy, except that the target array has to be set up by the caller. The target is not allocated or reallocated.

FUNCTION CopyData (BYVAL psaTarget AS SAFEARRAY PTR) AS HRESULT

On exit, the array referred to by psaTarget contains a copy of the data if the call succeeds.

Return value

S_OK (0) on success or an HREUSLT code.

CopyFrom

Copies the contents of the passed safe array.

FUNCTION CopyFrom (BYVAL psaSrc AS SAFEARRAY PTR) AS HRESULT

Return value

S_OK (0) on success or an HREUSLT code on failure.

Remarks

CopyFrom calls the string or variant manipulation functions if the array to copy contains either of these data types. If the array being copied contains object references, the reference counts for the objects are incremented.

CopyFromVariant

Copies the contents of a VARIANT of type VT_ARRAY to the object. The VARIANT remains unaltered.

FUNCTION CopyFromVariant (BYVAL pvar AS VARIANT PTR) AS HRESULT

pvar must be variant of type VT_ARRAY, i.e. containing a safe array. If it is of another type, an invalid data error is returned.

Return value

S_OK (0) on success or an HREUSLT code on failure.

Remarks

CopyFromVariant calls the string or variant manipulation functions if the array to copy contains either of these data types. If the array being copied contains object references, the reference counts for the objects are incremented.

CopyToVariant

Copies the safe array to the passed variant.

FUNCTION CopyToVariant (BYVAL pvar AS VARIANT PTR) AS HRESULT

pvar is a pointer to the variant where the safe array will be copied.

Return value

S_OK (0) on success or an HREUSLT code on failure.

Count

Returns the number of elements in the specified dimension of the array.

FUNCTION Count (BYVAL nDim AS UINT = 1) AS UINT

The optional nDim parameter is the array dimension for which to get the number of elements. You don't need to pass this parameter if the safe array in one-dimensional.

Return value

S_OK (0) on success or an HREUSLT code on failure.

Create

Creates a safe array from the given VARTYPE, number of dimensions and bounds.

Multidimensional array:

FUNCTION Create (BYVAL vt AS VARTYPE, BYVAL cDims AS UINT, BYVAL prgsabound AS SAFEARRAYBOUND PTR) AS HRESULT

One-dimensional array:

FUNCTION Create (BYVAL vt AS VARTYPE, BYVAL cElements AS ULONG, BYVAL lLBound AS LONG) AS HRESULT

Two-dimensional array:

FUNCTION Create (BYVAL vt AS VARTYPE, BYVAL cElements1 AS ULONG, BYVAL lLBound1 AS LONG, _
   BYVAL cElements2 AS ULONG, BYVAL lLBound2 AS LONG) AS HRESULT

Return value

S_OK (0) on success or an HREUSLT code on failure.

CreateEx

Creates a safe array from the given VARTYPE, number of dimensions and bounds.

Multidimensional array:

FUNCTION CreateEx (BYVAL vt AS VARTYPE, BYVAL cDims AS UINT, _
   BYVAL prgsabound AS SAFEARRAYBOUND PTR, BYVAL pvExtra AS PVOID) AS HRESULT

One-dimensional array:

FUNCTION CreateEx (BYVAL vt AS VARTYPE, BYVAL cElements AS ULONG, _
   BYVAL lLBound AS LONG, BYVAL pvExtra AS PVOID) AS HRESULT

Two-dimensional array:

FUNCTION CreateEx (BYVAL vt AS VARTYPE, BYVAL cElements1 AS ULONG, BYVAL lLBound1 AS LONG, _
   BYVAL cElements2 AS ULONG, BYVAL lLBound2 AS LONG, BYVAL pvExtra AS PVOID) AS HRESULT

Return value

S_OK (0) on success or an HRESULT code on failure.

CreateVector

Creates a fixed size safe array from the given VARTYPE, lower bound and number of elements.

FUNCTION CreateVector (BYVAL vt AS VARTYPE, BYVAL cElements AS ULONG, BYVAL lLBound AS LONG) AS HRESULT

Return value

S_OK (0) on success or an HRESULT code on failure.

Remarks

CreateVector allocates a single block of memory containing a SAFEARRAY structure for a single-dimension array (24 bytes), immediately followed by the array data. All of the existing safe array functions work correctly for safe arrays that are allocated with CreateVector.

A safe array created with CreateVector is allocated as a single block of memory. Both the SafeArray descriptor and the array data block are allocated contiguously in one allocation, which speeds up array allocation. However, a user can allocate the descriptor and data area separately using the SafeArrayAllocDescriptor and SafeArrayAllocData* calls.

CreateVectorEx

Creates a fixed size safe array from the given VARTYPE, lower bound and number of elements.

FUNCTION CreateVectorEx (BYVAL vt AS VARTYPE, BYVAL cElements AS ULONG, BYVAL lLBound AS LONG, _
   BYVAL pvExtra AS ANY PTR) AS HRESULT

Return value

S_OK (0) on success or an HRESULT code on failure.

Destroy

Destroys an existing array descriptor and all of the data in the array. If objects are stored in the array, Release is called on each object in the array.

FUNCTION Destroy () AS HRESULT

Return value

S_OK (0) on success or an HRESULT code on failure.

Detach

Detaches the safe array descriptor from the CSafeArray.

FUNCTION Detach () AS SAFEARRAY PTR

Return value

Returns a pointer to a SAFEARRAY descriptor.

Remarks

The caller takes ownership of it and must destroy it when no longer needed.

ElemSize

Returns the size of an element.

FUNCTION ElemSize () AS UINT

Return value

Returns the size (in bytes) of an element in a safe array. Does not include size of pointed-to data.

Features / Flags

Returns the flags used by the safe array. This is the same that the Flags method.

FUNCTION Features () AS USHORT

Find

Scans the array to search for the specified string.

FUNCTION Find (BYREF wszFind AS WSTRING, BYVAL bNoCase AS BOOLEAN = FALSE) AS LONG

Return value

The index of the retrieved array element, or 0 on failue.

Get / GetStr / GetVar

Retrieves a single element of the array.

Multidimensional array:

FUNCTION Get (BYVAL prgIndices AS LONG PTR, BYVAL pData AS ANY PTR) AS HRESULT
FUNCTION Get (BYVAL prgIndices AS LONG PTR, BYREF cbsData AS CBSTR) AS HRESULT
FUNCTION Get (BYVAL prgIndices AS LONG PTR, BYREF cvData AS CVAR) AS HRESULT
FUNCTION GetStr (BYVAL prgIndices AS LONG PTR) AS CBSTR
FUNCTION GetVar (BYVAL prgIndices AS LONG PTR) AS CVAR

One-dimensional array:

FUNCTION Get (BYVAL idx AS LONG, BYVAL pData AS ANY PTR) AS HRESULT
FUNCTION Get (BYVAL idx AS LONG, BYREF cbsData AS CBSTR) AS HRESULT
FUNCTION Get (BYVAL idx AS LONG, BYREF cvData AS CVAR) AS HRESULT
FUNCTION GetStr (BYVAL idx AS LONG) AS CBSTR
FUNCTION GetVar (BYVAL idx AS LONG) AS CVAR

Two-dimensional array:

FUNCTION Get (BYVAL cElem AS LONG, BYVAL cDim AS LONG, BYVAL pData AS ANY PTR) AS HRESULT
FUNCTION Get (BYVAL cElem AS LONG, BYVAL cDim AS LONG, BYREF cbsData AS CBSTR) AS HRESULT
FUNCTION Get (BYVAL cElem AS LONG, BYVAL cDim AS LONG, BYREF cvData AS CVAR) AS HRESULT
FUNCTION GetStr (BYVAL cElem AS LONG, BYVAL cDim AS LONG) AS CVAR
FUNCTION GetVar (BYVAL cElem AS LONG, BYVAL cDim AS LONG) AS CVAR

First element, then dimension, e.g. 2, 1 (element 2, first dimension), 1, 2 (element 1, 2nd dimension).

Usage example

' // One-dimensional array of VT_BSTR
DIM csa AS CSafeArray = CSafeArray(VT_BSTR, 2, 1)
csa.PutStr(1, "Test string 1")
print csa.GetStr(1)
csa.PutStr(2, "Test string 2")
print csa.GetStr(2)

' // One-dimensional array of VT_VARIANT
DIM csa AS CSafeArray = CSafeArray(VT_VARIANT, 5, 1)
DIM cv1 AS CVAR = "Test variant 1"
csa.Put(1, cv1)
DIM cvOut AS CVAR
csa.Get(1, cvOut)
print cvOut
DIM cv2 AS CVAR = "Test variant 2"
csa.Put(1, cv2)
csa.Get(1, cvOut)
print cvOut

' // Two-dimensional array of BSTR
' // 2D: elements = 5, lower bound = 1
' // 2D: elements = 3, lower bound = 1
DIM rgsabounds(0 TO 1) AS SAFEARRAYBOUND = {(5, 1), (3, 1)}
DIM csa AS CSafeArray = CSafeArray(VT_BSTR, 2, @rgsabounds(0))

' // array index: first element, first dimension
DIM rgidx(0 TO 1) AS LONG = {1, 1}
DIM cbs1 AS CBSTR = "Test string 1"
' // Put the value
csa.Put(@rgidx(0), cbs1)
' // Get the value
DIM cbsOut AS CBSTR
csa.Get(@rgidx(0), cbsOut)
print cbsOut
' // array index: second element, first dimension
rgidx(0) = 2 : rgidx(1) = 1
' // Put the value
DIM cbs2 AS CBSTR = "Test string 2"
csa.Put(@rgidx(0), cbs2)
' // Get the value
csa.Get(@rgidx(0), cbsOut)
print cbsOut

' // array index: first element, second dimension
rgidx(0) = 1 : rgidx(1) = 2
' // Put the value
DIM cbs3 AS CBSTR = "Test string 3"
csa.Put(@rgidx(0), cbs3)
' // Get the value
csa.Get(@rgidx(0), cbsOut)
print cbsOut

' // array index: second element, second dimension
rgidx(0) = 2 : rgidx(1) = 2
' // Put the value
DIM cbs4 AS CBSTR = "Test string 4"
csa.Put(@rgidx(0), cbs4)
' // Get the value
csa.Get(@rgidx(0), cbsOut)
print cbsOut

Return value (Get)

S_OK (0) on success or an HRESULT code on failure.

Return value (GetStr / GetVar)

The string or variant element.

Remarks

This method calls SafearrayLock and SafearrayUnlock automatically, before and after retrieving the element. The caller must provide a storage area of the correct size to receive the data. If the data element is a string, object, or variant, the function copies the element in the correct way.

GetIID

Returns the GUID of the interface contained within a given safe array.

FUNCTION GetIID () AS GUID

Return value

The GUID of the interface, on success, or a null guid on failure.

GetRecordInfo

Retrieves the IRecordInfo interface of a UDT contained in a given safe array.

FUNCTION GetRecordInfo () AS IRecordInfo PTR

GetType

Returns the VARTYPE stored in the given safe array.

FUNCTION GetType () AS VARTYPE

Insert

Inserts a value at the specified position of the safe array.

FUNCTION Insert (BYVAL nPos AS LONG, BYVAL pData AS ANY PTR) AS HRESULT
FUNCTION Insert (BYVAL nPos AS LONG, BYREF cbsData AS CBSTR) AS HRESULT
FUNCTION Insert (BYVAL nPos AS LONG, BYREF cvData AS CVAR) AS HRESULT
FUNCTION Insert (BYVAL nPos AS LONG, BYVAL vData AS VARIANT) AS HRESULT

Inserts a value at the beginning of the safe array.

FUNCTION Insert (BYVAL pData AS ANY PTR) AS HRESULT
FUNCTION Insert (BYREF cbsData AS CBSTR) AS HRESULT
FUNCTION Insert (BYREF cvData AS CVAR) AS HRESULT
FUNCTION Insert (BYVAL vData AS VARIANT) AS HRESULT

Inserts a string.

FUNCTION InsertStr (BYVAL nPos AS LONG, BYVAL pwszData AS WSTRING PTR) AS HRESULT
FUNCTION InsertStr (BYVAL pwszData AS WSTRING PTR) AS HRESULT

Return value

S_OK (0) on success or an HRESULT code on failure.

Usage example

' // Create a one-dimensional array of variants
'DIM csa AS CSafeArray = CSafeArray(VT_VARIANT, 2, 1)
DIM csa AS CSafeArray = CSafeArray("VARIANT", 2, 1)

csa.Put(1, CVAR("Test string 1"))
csa.Put(2, CVAR("Test string 2"))
csa.Insert(2, CVAR(12345.67, "DOUBLE"))

DIM cvOut AS CVAR
csa.Get(1, cvOut)
print cvOut
csa.Get(2, cvOut)
print cvOut
csa.Get(3, cvOut)
print cvOut

IsResizable

Tests if the safe array can be resized.

FUNCTION IsResizable () AS BOOLEAN

Return value

TRUE if the array can be resized; FALSE, otherwise.

LBound

Returns the lower bound for any dimension of a safe array.

FUNCTION LBound (BYVAL nDim AS UINT = 1) AS LONG

LBound

Returns the lower bound for any dimension of a safe array.

FUNCTION LBound (BYVAL nDim AS UINT = 1) AS LONG

UBound

Returns the upper bound for any dimension of a safe array.

FUNCTION UBound (BYVAL nDim AS UINT = 1) AS LONG

LocksCount

Returns the number of times the array has been locked without the corresponding unlock.

FUNCTION LocksCount () AS UINT

MoveFromVariant

Transfers ownership of the safe array contained in the variant parameter to this object. The variant is then changed to VT_EMPTY.

FUNCTION MoveFromVariant (BYVAL pvar AS VARIANT PTR) AS HRESULT

Return value

S_OK (0) on success or an HRESULT code on failure.

MoveToVariant

Transfers ownership of the safe array to a variant and detaches it from the class.

FUNCTION MoveToVariant (BYVAL pvar AS VARIANT PTR) AS HRESULT

Usage example

' // One-dimensional array of VT_BSTR
DIM csa AS CSafeArray = CSafeArray(VT_BSTR, 2, 1)
csa.Put(1, CBSTR("Test string 1"))
DIM cbsOut AS CBSTR
csa.Get(1, cbsOut.vptr)
print cbsOut
csa.Put(2, CBSTR("Test string 2"))
csa.Get(2, cbsOut)
print cbsOut

DIM v AS VARIANT
csa.MoveToVariant(@v)
print AfxVarToStr(@v)
VariantClear @v

Return value

S_OK (0) on success or an HRESULT code on failure.

NumDims

Returns the number of dimensions in the array.

FUNCTION NumDims () AS UINT

PtrOfIndex

Returns a pointer to an array element.

Multidimensional array:

FUNCTION PtrOfIndex (BYVAL prgIndices AS LONG PTR) AS ANY PTR

One-dimensional array:

FUNCTION PtrOfIndex (BYVAL idx AS LONG) AS HRESULT

Two-dimensional array:

FUNCTION PtrOfIndex (BYVAL cElem AS LONG, BYVAL cDim AS LONG) AS HRESULT

Put

Stores the data element at a given location in the array.

Multidimensional array:

FUNCTION Put (BYVAL prgIndices AS LONG PTR, BYVAL pData AS ANY PTR) AS HRESULT
FUNCTION PutStr (BYVAL prgIndices AS LONG PTR, BYREF cbsData AS CBSTR) AS HRESULT
FUNCTION PutVar (BYVAL prgIndices AS LONG PTR, BYREF cvData AS CVAR) AS HRESULT

One-dimensional array:

FUNCTION Put (BYVAL idx AS LONG, BYVAL pData AS ANY PTR) AS HRESULT
FUNCTION PutStr (BYVAL idx AS LONG, BYREF cbsData AS CBSTR) AS HRESULT
FUNCTION PutVar (BYVAL idx AS LONG, BYREF cvData AS CVAR) AS HRESULT

Two-dimensional array:

FUNCTION Put (BYVAL cElem AS LONG, BYVAL cDim AS LONG, BYVAL pData AS ANY PTR) AS HRESULT
FUNCTION PutStr (BYVAL cElem AS LONG, BYVAL cDim AS LONG, BYREF cbsData AS CBSTR) AS HRESULT
FUNCTION PutVar (BYVAL cElem AS LONG, BYVAL cDim AS LONG, BYREF cvData AS CVAR) AS HRESULT

Return value

S_OK (0) on success or an HRESULT code on failure.

Remarks

This function automatically calls SAfeArrayLock and SafeArrayUnlock before and after assigning the element. If the data element is a string, object, or variant, the function copies it correctly when the safe array is destroyed. If the existing element is a string, object, or variant, it is cleared correctly. If the data element is a VT_DISPATCH or VT_UNKNOWN, AddRef is called to increment the object's reference count.

Multiple locks can be on an array. Elements can be put into an array while the array is locked by other operations.

Redim

Changes the right-most (least significant) bound of a safe array.

Multidimensional array:

FUNCTION Redim (BYVAL pnewsabounds AS SAFEARRAYBOUND PTR) AS HRESULT

One-dimensional array:

FUNCTION Redim (BYVAL cElements AS ULONG, BYVAL lLBound AS LONG) AS HRESULT

Two-dimensional array:

FUNCTION Redim (BYVAL cElements1 AS ULONG, BYVAL lLBound1 AS LONG, _
   BYVAL cElements2 AS ULONG, BYVAL lLBound2 AS LONG) AS HRESULT

Usage example

' // One-dimensional array of VT_VARIANT
' // Two elements, lower-bound 1
'DIM csa AS CSafeArray = CSafeArray(VT_VARIANT, 2, 1)
DIM csa AS CSafeArray = CSafeArray("VARIANT", 2, 1)
DIM cv1 AS CVAR = "Test variant 1"
csa.Put(1, cv1)
DIM cvOut AS CVAR
csa.Get(1, cvOut)
print cvOut

DIM cv2 AS CVAR = "Test variant 2"
csa.Put(1, cv2)
csa.Get(1, cvOut)
print cvOut

' // Redim (preserve) the safe array
csa.Redim(1, 3)
DIM cv3 AS CVAR = "Test variant 3"
csa.Put(3, cv3)
csa.Get(3, cvOut)
print cvOut

Return value

S_OK (0) on success or an HRESULT code on failure.

Remove

Removes the specified array element.

FUNCTION Remove (BYVAL nPos AS LONG) AS HRESULT
FUNCTION RemoveStr (BYVAL nPos AS LONG) AS HRESULT
FUNCTION RemoveVar (BYVAL nPos AS LONG) AS HRESULT

Return value

S_OK (0) on success or an HRESULT code on failure.

SetIID

Sets the IID (a GUID) of the interface contained within a given safe array.

FUNCTION SetIID (BYVAL pguid AS GUID PTR) AS HRESULT

Return value

S_OK (0) on success or an HRESULT code on failure.

SetRecordInfo

Sets the IRecordInfo interface of the UDT contained in a given safe array.

FUNCTION SetRecordInfo (BYVAL prinfo AS IRecordInfo PTR) AS HRESULT

Return value

S_OK (0) on success or an HRESULT code on failure.

Sort

Sorts a one-dimensional VT_BSTR CSafeArray calling the C qsort function.

FUNCTION Sort (BYVAL bAscend AS BOOLEAN = TRUE) AS HRESULT

Return value

S_OK (0) on success or an HRESULT code on failure.

Usage example

' // Create a one-dimensional array of BSTR
DIM csa AS CSafeArray = CSafeArray(VT_BSTR, 3, 1)

DIM cbsVal AS CBSTR = "bcde"
csa.Put(1, cbsVal)
cbsVal = "abc"
csa.Put(2, cbsVal)
cbsVal = "abcfg"
csa.Put(3, cbsVal)
' // Sort the safe array
csa.Sort

csa.Get(1, cbsVal)
print cbsVal
csa.Get(2, cbsVal)
print cbsVal
csa.Get(3, cbsVal)
print cbsVal

--- or ---

print csa.GetStr(1)
print csa.GetStr(2)
print csa.GetStr(3)

UnaccessData

Decrements the lock count of an array, and invalidates the pointer retrieved by AccessData.

FUNCTION UnaccessData () AS HRESULT

Return value

S_OK (0) on success or an HRESULT code on failure.